Codex CLI 安装与配置手册（接入 内部网关）
适用环境：Ubuntu 22.04
网关地址：https://<your-gateway-domain>
一、安装 Codex CLI
官方一键安装脚本，不依赖 Node.js：
curl -fsSL https://chatgpt.com/codex/install.sh | sh
脚本会自动识别系统架构（x86-64 / ARM64），下载对应二进制并加入 PATH。
验证安装
codex --version # 确认版本号正常输出
command -v codex # 确认 codex 命令在 PATH 中
可选依赖：Bubblewrap（命令执行沙箱）
sudo apt update && sudo apt install -y bubblewrap
常见安装问题
| 现象 | 原因 / 处理 |
|---|---|
codex: command not found |
安装目录未加入 PATH，检查 ~/.bashrc，source ~/.bashrc |
二、配置接入内部网关
配置文件路径：~/.codex/config.toml（仅 user-level 生效，Codex 不支持项目级 override）
注意：该文件不会自动生成，需要手动创建。
最终生效配置（已验证可用）
model = "<your-model-alias>"
model_provider = "<provider-name>"
preferred_auth_method = "apikey"
forced_login_method = "api"
model_reasoning_effort = "high"
approvals_reviewer = "user"
[model_providers.<provider-name>]
name = "<provider-name>"
base_url = "https://<your-gateway-domain>/v1"
wire_api = "responses"
experimental_bearer_token = "sk-<YOUR_API_KEY>"
将 sk-<YOUR_API_KEY> 替换为实际网关 API Key，然后：
cp config.toml ~/.codex/config.toml
codex
字段说明
| 字段 | 说明 |
|---|---|
model |
网关侧配置的模型别名，需和网关 model group 名称一致 |
model_provider |
对应下方 [model_providers.xxx] 的 key |
base_url |
必须带 /v1（/v1 是 OpenAI 兼容路由，Chat Completions / Responses 都走这里；不带 /v1 的根路径是给 Claude Code 这类走 Anthropic /v1/messages 协议的客户端用的，两者不要混用） |
wire_api |
Codex 0.59+ 版本只支持 "responses"，"chat" 已被移除 |
experimental_bearer_token |
直接明文写 key，能用但官方不推荐（更安全的做法见下方"可选：用环境变量"） |
preferred_auth_method / forced_login_method |
设为 "apikey" / "api"，跳过 ChatGPT 账号登录，强制走 API Key 认证 |
可选：用环境变量代替明文 Key（更安全）
[model_providers.<provider-name>]
...
env_key = "TS_LLM_API_KEY" # 这里填的是环境变量的名字，不是 key 本身
export TS_LLM_API_KEY="sk-<YOUR_API_KEY>" # 建议写进 ~/.bashrc 持久化
踩坑记录：
env_key曾被误填成 key 本身（env_key = "sk-<YOUR_API_KEY>"），导致报错Missing environment variable: sk-<YOUR_API_KEY>...——因为 Codex 把这个值当成变量名去环境里找，而不是直接当 key 用。
三、排障记录
1. Error loading configuration: No such file or directory (os error 2)
原因：model_catalog_json = "~/.codex/models.json" —— TOML 不做 ~ 展开，Codex 会把它当字面路径去找，文件不存在就报错。
处理：删掉这一行；若确需自定义模型目录，改成绝对路径（如 /home/用户名/.codex/models.json）并确保文件存在。
2. Model metadata for <your-model-alias> not found. Defaulting to fallback metadata
黄色警告，非致命错误。Codex 内置模型参数表没收录这个自定义模型名，会用默认参数兜底，不影响正常使用，可忽略。
四、快速复用清单
# 1. 安装
curl -fsSL https://chatgpt.com/codex/install.sh | sh
sudo apt install -y bubblewrap
# 2. 配置
cp config.toml ~/.codex/config.toml # 内容见上方"最终生效配置"
# 3. 验证
codex --version
codex